Prior versions of Tools Plus did not allow odd length editing field strings (except for Str255). This was due to a carry-over from THINK Pascal which rounds string structures to even byte boundaries (i.e., a string[20] reserves 20 bytes for the characters, plus 1 length byte, then rounded up to 22 bytes).
As a result of this rounding phenomenon, prior versions of Tools Plus would “round down” the logical length of a string (because a 14 character and 15 character field _both_ produced a 16 byte structure in THINK Pascal).
To remedy this anomaly, a new NewStrHandle routine has been provided to let you create initialized string handles that are exactly the right size. C/C++ programmers can still opt to use the toolbox’s NewHandle routine in conjunction with the sizeof routine.
You will probably have to modify your existing application(s) to use the NewStrHandle routine instead of NewHandle.
Please add the following note to page 82 of the printed manual:
Note: Your application must allocate memory for each handle that it
provides to Tools Plus by using the NewHandle or Tools Plus’s
NewStrHandle routine. Tools Plus does not automatically
allocate this memory. If your editing fields contain random
characters, it is a sure sign that you have not allocated
memory for your handle.
Please add the following new routine to page 87 of the printed manual:
NewStrHandle
~~~~~~~~~~~
Allocate memory for a Pascal string, and initialize it to an empty string.
function NewStrHandle (StringLen: INTEGER): STRINGHANDLE;
StringLen is the size of the Pascal string (from 1 to 255 characters) being allocated. NewStrHandle automatically allocates one additional byte of heap memory to accommodate the entire Pascal string plus a length byte.
The function’s value returns a string handle to a Pascal string of the specified length. The string is initialized to an empty string (‘’), thus making is ready for immediate use with the NewField or NewFieldRect routines.
Please replace the third paragraph of the NewField description (on page 87 in the printed manual) with the following:
HStr is a handle that provides this field with a reference to its string. The handle can be generic, but it’s treated like a string handle by Tools Plus, in that the first byte of its memory block is a length byte and the remainder is the actual string. A copy of the hStr handle’s contents is used while the field is being edited. It is also used to automatically display an inactive edit field’s text when a window needs to be refreshed. Each field must have its own string. You must allocate memory for the handle and set it to a default string value before using it in the NewField routine. A good way to both allocate and initialize the handle is to use the NewStrHandle routine.
•• A new routine has been added (add to page 91) that lets your application determine if a field is empty without having to get its text.
FieldIsEmpty
~~~~~~~~~~
Determine if the specified field is empty.
pascal Boolean FieldIsEmpty (short Field);
function FieldIsEmpty (Field: INTEGER): BOOLEAN;
Field specifies the field number (from 1 to 255) that is queried in the current window.
The function’s value returns true if the field is empty (string length is zero). A non-zero length string returns a value of false. If the specified field is the window’s active editing field (even though the window itself may not be active at the time), the function is performed on the field’s edited text. Otherwise, the function is performed on the field’s string. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, FieldIsEmpty returns with a value of true.
•• A new event type has been added (add to page 109). This event will be ignored by most applications.
doPreRefresh (event)
~~~~~~~~~~~~~~~~
A window’s contents _may_ be refreshed (redrawn) before Tools Plus refreshes its own objects.
Most applications will ignore this event. A doPreRefresh event is reported before each doRefresh event (which occurs when a window is completely or partially obscured, then becomes uncovered and needs to be redrawn). The doPreRefresh event lets your application draw or display objects before Tools Plus draws its own objects (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls).
An example of the doPreRefresh event’s usefulness is if your application displays a picture as a background for a window. When your application receives a doPreRefresh event, it can draw the background picture only. The next time your application calls PollSystem, Tools Plus will refresh all its own objects and report a doRefresh event for your application to process.
When a doPreRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed. Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing.
Programming Considerations
~~~~~~~~~~~~~~~~~~~~~~
• When your application detects a doPreRefresh event, it should
respond in the following manner:
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only}
{ within the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat for each monitor }
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the }
{ window. }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
* BeginUpdate temporarily sets the window’s visRgn (visible region where drawing occurs) to the intersection of the visRgn and updateRgn (region requiring updating). This effectively restricts drawing to the area that needs updating. The affected area may include Tools Plus objects which are automatically refreshed the next time PollSystem is called.
* If your application did not put anything in the window except buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls, it should ignore the doPreRefresh event.
* It is possible that several windows will need to be refreshed simultaneously if, for instance, a closing window exposed three windows behind it. PollSystem reports a single doPreRefresh event (followed by a doRefresh event) each time it is called in the event loop, one event for each window that needs refreshing.
* Unlike ordinary Macintosh applications, a doPreRefresh event is not generated when a window is first opened.
* A doPreRefresh event is not generated for desk accessories, Dialog Manager dialogs, alerts, or Dynamic Alerts. These events are handled automatically.
* When responding to a doPreRefresh event, your application should limit itself to activities that pertain only to refreshing the specified window. Do not create or modify user interface elements, open, close, or move windows.
* Your application can easily do all its drawing in response to a doPreRefresh event, or a doRefresh event. If, however, your application wants to do some drawing in response to both events, you will need to get a copy of the affected window’s visRgn (visible region) while inside the BeginUpdate/EndUpdate structure (to determine the region that is affected by the doPreRefresh drawing). After you finish refreshing the window and you have called EndUpdate, invalidate the affected region by using InvalRgn. This will ensure that your application will redraw the necessary objects in response to the doRefresh event.
•• A new event type has been added (add to page 178). This event will be ignored by most applications.
doChgInField (event)
~~~~~~~~~~~~~~~~
Indicator that the contents of your application’s active editing field have been changed.
The doChgInField event is reported whenever the active field in your application is altered, either through typing, cutting, pasting (including the use of the PasteIntoField routine), clearing, or undoing/redoing (using the Edit menu). Most applications will ignore this event.
•• The following note has been added to the User Manual. It pertains to C programmers compiling the Tools Plus Demo application…
IMPORTANT! Errors when compiling the Demo…
At the time of this writing, Water’s Edge Software has made every effort to ensure that our demo application will compile successfully the first time. Unfortunately, Symantec C/C++ compilers have undergone a series of revisions and some inconsistencies have arisen between compiler versions. Fortunately, these differences are simple to resolve.
If your compiler gives you an error that states “argument to function ‘x’ does not match prototype,” it indicates that Symantec has made a minor revision to that function’s prototype (in the error message, ‘x’ will be replaced by the function’s name). To correct this error, inspect the offending line in the source file, which is likely a line like:
PenPat(&gray);
and revise it to match the prototype in the related header file. In the example above, the correction is as simple as changing the line to:
PenPat(gray); /* Remove ampersand (&) from the variable */
To date, all inconsistencies have been of this nature. We are sorry for the inconvenience these issues may cause you, and would like to offer our assistance if you have problems getting the demo compiled. See the “Technical Support” chapter for information on how to contact Water’s Edge Software for assistance.
